/**
 * @title Auditor WebDiff-UI
 * @type jQuery-based Plug-in Script
 * @version 0.1.1 [pre-release development versions]
 * @author Trungtin Ton
 * @license ... (Red Hat Inc.)
 * 
 */

/**
 * <h1>Auditor WebDiff-UI</h1>
 * <h2>PLUGIN DESCRIPTION:</h2>
 * <p>
 * This jQuery-based plugin script contains all of the required client-side
 * functionality for enabling the use of the Auditor WebDiff tool. It provides a
 * comprehensive API for browser client-side operations and both synchronous and
 * asynchronous server-side interaction, and can be easily extended or
 * configured to suit the design of any given application (without having to
 * hardcode or recode the plugin's internal implementation).
 * <p>
 * When attached to any Auditor-compatible web application, the plugin API
 * allows a client to safely (either synchronously or asynchronously) push
 * documents to the server and subsequently retrieve, parse, extract and display
 * the output data, in accordance with the API for Auditor WebDiff. In addition
 * to these AJAX operations, the plugin provides abstracted functions and
 * handlers that can be quickly and easily bound to on-page ui elements. They
 * are included for the convenience and benefit of programmers, so as to limit
 * the need to fiddle with low-level functionality.
 * <p>
 * The full version of the plugin contains the API along with a simple, elegant
 * and comprehensive widget-like ui appliance that leverages the API provided
 * below. The ui plugin for this script is designed and packaged separately from
 * the client API, so programmers that wish to build their own ui for their web
 * application can ignore or discard the ui plugin and utilize the API only
 * instead.
 * 
 * <h2>DEVELOPER NOTES</h2>
 * 
 * TODO: remove console.error tokens and employ user notifications if applicable
 * 
 * TODO: refactor modules into separate plugin components
 * 
 * TODO: iterate and extend code
 * 
 * XXX This plugin is currently not in use, as it currently cannot support
 * asynchronous file uploads, and also does not support multiple input types in
 * one request. Until these are implemented, WebDiff UI will use standard forms
 * instead.
 * 
 */
(function($) {
	"use strict";

	/**
	 * Entry point to the WebDiff client functionality (which in turn interfaces
	 * with the server side once configured).
	 */
	$.fn.webdiff = {

		/**
		 * Executes a complete WebDiff Compare operation, from the given valid
		 * HTML documents. This function automatically retrieves and parses the
		 * result, returning a jQuery object containing the valid HTML response
		 * to be inserted onto the page.
		 * 
		 * @param srcInput
		 *            the content of the source document input.
		 * @param destInput
		 *            the content of the destination document input.
		 * @return the parsed result of the comparison retrieved from the
		 *         server.
		 * @note There is no public API for WebDiff's services at the moment:
		 *       for now, the general parameters for invoking a WebDiff compare
		 *       are a "dest" and a "source". This may only be specified as a
		 *       URL. Direct input and File upload are not yet supported.
		 * 
		 * TODO: create a public WebDiff server-side API and remove this note.
		 */
		compare : function(srcInput, destInput) {
			var result = undefined;

			$.ajax({
				"async" : true,
				"cache" : false,
				"type" : "POST",
				"url" : "/auditor/webdiff/compare",
				"dataType" : "html",
				"data" : {
					"source" : srcInput,
					"dest" : destInput
				}
			}).done(function(response, textStatus, jqXHR) {
				$("body").html(response);
				result = response;

			}).fail(function(jqXHR, textStatus, errorThrown) {
				console.error(textStatus + ": " + errorThrown);

			}).always(function(jqXHR, textStatus) {
				console.info("AJAX request complete");
			});
			return result;
		}
	};

})(jQuery);